.TH std::move_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::move_iterator \- std::move_iterator

.SH Synopsis
   Defined in header <iterator>
   template< class Iter >        \fI(since C++11)\fP
   class move_iterator;

   std::move_iterator is an iterator adaptor which behaves exactly like the underlying
   iterator (which must be at least a LegacyInputIterator
   or model input_iterator
   \fI(since C++20)\fP
   , or stronger iterator concept
   (since C++23)), except that dereferencing converts the value returned by the
   underlying iterator into an rvalue. If this iterator is used as an input iterator,
   the effect is that the values are moved from, rather than copied from.

.SH Member functions

   constructor                  constructs a new iterator adaptor
   \fI(C++11)\fP                      \fI(public member function)\fP
   operator=                    assigns another iterator adaptor
   \fI(C++11)\fP                      \fI(public member function)\fP
   base                         accesses the underlying iterator
   \fI(C++11)\fP                      \fI(public member function)\fP
   operator*
   operator->                   accesses the pointed-to element
   \fI(C++11)\fP                      \fI(public member function)\fP
   \fI(C++11)\fP(deprecated in C++20)
   operator[]                   accesses an element by index
   \fI(C++11)\fP                      \fI(public member function)\fP
   operator++
   operator++(int)
   operator+=
   operator+                    advances or decrements the iterator
   operator--                   \fI(public member function)\fP
   operator--(int)
   operator-=
   operator-
   \fI(C++11)\fP

.SH Non-member functions

   operator==
   operator!=
   operator<
   operator<=
   operator>
   operator>=
   operator<=>                    compares the underlying iterators
   \fI(C++11)\fP                        \fI(function template)\fP
   \fI(C++11)\fP(removed in C++20)
   \fI(C++11)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP
   (C++20)
   operator==(std::move_sentinel) compares the underlying iterator and the underlying
   (C++20)                        sentinel
                                  \fI(function template)\fP
   operator+                      advances the iterator
   \fI(C++11)\fP                        \fI(function template)\fP
   operator-                      computes the distance between two iterator adaptors
   \fI(C++11)\fP                        \fI(function template)\fP
   operator-(std::move_sentinel)  computes the distance between the underlying iterator
   (C++20)                        and the underlying sentinel
                                  \fI(function template)\fP
   iter_move                      casts the result of dereferencing the underlying
   (C++20)                        iterator to its associated rvalue reference type
                                  \fI(function)\fP
   iter_swap                      swaps the objects pointed to by two underlying
   (C++20)                        iterators
                                  \fI(function template)\fP
   make_move_iterator             creates a std::move_iterator of type inferred from
   \fI(C++11)\fP                        the argument
                                  \fI(function template)\fP

   Helper templates

   template< class Iterator1, class Iterator2 >

       requires (!std::sized_sentinel_for<Iterator1, Iterator2>)
   constexpr bool disable_sized_sentinel_for<                     \fI(since C++20)\fP
       std::move_iterator<Iterator1>,

       std::move_iterator<Iterator2>> = true;

   This partial specialization of std::disable_sized_sentinel_for prevents
   specializations of move_iterator from satisfying sized_sentinel_for if their
   underlying iterators do not satisfy the concept.

.SH Notes

         Feature-test macro         Value    Std                 Feature
   __cpp_lib_move_iterator_concept 202207L (C++23) Make std::move_iterator<T*> a random
                                                   access iterator

.SH Example


// Run this code

 #include <algorithm>
 #include <iomanip>
 #include <iostream>
 #include <iterator>
 #include <ranges>
 #include <string>
 #include <string_view>
 #include <vector>

 void print(const std::string_view rem, const auto& v)
 {
     std::cout << rem;
     for (const auto& s : v)
         std::cout << std::quoted(s) << ' ';
     std::cout << '\\n';
 };

 int main()
 {
     std::vector<std::string> v{"this", "_", "is", "_", "an", "_", "example"};
     print("Old contents of the vector: ", v);
     std::string concat;
     for (auto begin = std::make_move_iterator(v.begin()),
               end = std::make_move_iterator(v.end());
          begin != end; ++begin)
     {
         std::string temp{*begin}; // moves the contents of *begin to temp
         concat += temp;
     }

     // Starting from C++17, which introduced class template argument deduction,
     // the constructor of std::move_iterator can be used directly:
     // std::string concat = std::accumulate(std::move_iterator(v.begin()),
     //                                      std::move_iterator(v.end()),
     //                                      std::string());

     print("New contents of the vector: ", v);
     print("Concatenated as string: ", std::ranges::single_view(concat));
 }

.SH Possible output:

 Old contents of the vector: "this" "_" "is" "_" "an" "_" "example"
 New contents of the vector: "" "" "" "" "" "" ""
 Concatenated as string: "this_is_an_example"

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied               Behavior as published               Correct behavior
              to
                    dereferencing a move_iterator could return a
   LWG 2106 C++11   dangling reference                                returns the
                    if the dereferencing the underlying iterator      object instead
                    returns a prvalue
   LWG 3736 C++20   move_iterator was missing                         added
                    disable_sized_sentinel_for specialization
                    member iterator_category was defined even if      iterator_category
   P2259R1  C++20   std::iterator_traits<Iter>::iterator_category is  is
                    not defined                                       not defined in
                                                                      this case

.SH See also

   make_move_iterator creates a std::move_iterator of type inferred from the argument
   \fI(C++11)\fP            \fI(function template)\fP
   move_sentinel      sentinel adaptor for use with std::move_iterator
   (C++20)            \fI(class template)\fP
